docs/develop/net/Network Stack Overview.html

   1 <html>
   2 <body bgcolor=white>
   3         <h1>Haiku Network Stack Architecture</h1>
   4         <p>
   5         The Haiku Network Stack is a modular and layered networking stack, very
   6         similar to what you may know as BONE.
   7         </p>
   8         <p>
   9         The entry point when talking to the stack is through a dedicated device
  10         driver that publish itself in /dev/net. The userland library libnetwork.so
  11         (which combines libsocket.so, and libbind.so) directly talks to this
  12         driver, mostly via ioctl()<sup><a href="#foot1">1</a></sup>.
  13         </p>
  14         The driver either creates sockets, or passes on every command to the socket
  15         module<sup><a href="#foot2">2</a></sup>. Depending on the address family and
  16         type of the sockets, the lower layers will be loaded and connected.
  17         </p>
  18         <p>
  19         For example, with a TCP/IP socket, the stack could look like this:
  20         <table cellspacing=1 cellpadding=5 border=0>
  21                 <tr><td colspan=2 bgcolor="#aaaadd">Socket</td></tr>
  22                 <tr><td bgcolor="#ccccff">TCP</td>
  23                         <td rowspan=2 bgcolor="#ddddff"><p>Protocols<br>
  24                                 <font size="-2">defined by the socket (address family, type)</p>
  25                                 (session, transport, network layers)</font></td>
  26                 </tr>
  27                 <tr><td bgcolor="#ccccff">IPv4</td></tr>
  28                 <tr><td colspan=2 bgcolor="#ddcc88">Datalink</td></tr>
  29                 <tr><td bgcolor="#ffee88">ARP</td>
  30                         <td rowspan=2 bgcolor="#ffee99"><p>Datalink Protocols<br>
  31                                 <font size="-2">defined by the interface (IP address, device)</p>
  32                                 (datalink layer)</font></td>
  33                 </tr>
  34                 <tr><td bgcolor="#ffee88">Ethernet framing</td></tr>
  35                 <tr><td bgcolor="#ffdd00">Ethernet device</td><td bgcolor="#ffdd55"><font size="-2">(physical layer)</font></tr>
  36         </table>
  37         Where TCP, and IPv4 are net_protocol modules, and ARP, and the Ethernet framing are
  38         net_datalink_protocol modules. All modules are connected in a chain, even though the
  39         datalink layer introduces more than one path (one for each interface).
  40         </p>
  41         <p>
  42         When sending data through a socket, a net_buffer is created in the socket module, and passed
  43         on to the lower levels where each protocol processes it, before passing it on to the next
  44         protocol in the chain. The last protocol in the chain is always a domain protocol - it will
  45         directly forward the buffers to the datalink module. When the buffer reaches the datalink
  46         level, an accompanied net_route object will determine for which interface (which determines
  47         the datalink protocols in the chain) the buffer is destined. The route has to be specified
  48         by the upper protocols before the buffer gets into the datalink level - if a buffer comes
  49         in without a valid route, it is discarded.
  50         </p>
  51         <p>
  52         The protocol modules are loaded and unloaded as needed. The stack itself stays loaded
  53         as long as there are interfaces defined - as soon as the last interface is removed,
  54         the stack gets unloaded (which is, of course, not yet implemented).
  55         </p>
  56         <h3>The Structures and Classes</h3>
  57         <h4>net_domain</h4>
  58         <p>
  59         Every supported address family gets its own domain. A domain comprises such a family,
  60         a net_protocol module that handles this domain, and a list of interfaces and routes.
  61         It also gets a name: for example, the IPv4 module registers the "internet" domain
  62         (AF_INET).
  63         </p>
  64         <p>
  65         The domain protocol module is responsible for managing the domain; it has to register
  66         it when it's loaded, and it has to unregister it when it is unloaded by the networking
  67         stack.
  68         </p>
  69         <h4>net_interface</h4>
  70         <p>
  71         An interface makes an underlying net_device accessible by the stack. When creating
  72         a new interface, you have to specify a domain, and a device to be used. The stack
  73         will then look through the registered datalink protocols, and builds a chain of
  74         them for that interface.
  75         </p>
  76         <p>
  77         The interface usually gets a network address, and a route that directs buffers to
  78         be sent to it. If there is no route to an interface, it will never be used for
  79         outgoing data, but may well receive data from other hosts.
  80         </p>
  81         <p>
  82         An interface can be "up" (when <code>IFF_UP</code> is set in its <code>flags</code>
  83         member) in which case it accepts data - when that flag is not set, it will discard
  84         all data it gets. The interface also specifies the maximum buffer size that can be
  85         sent over this interface (the <code>mtu</code> member, a.k.a. maximum transmission
  86         unit).
  87         </p>
  88         <p>
  89         Interfaces are configured via ioctl()s (SIOCAIFADDR, ...). You can use the command
  90         line tool "ifconfig" to do this for you.
  91         </p>
  92         <h4>net_device</h4>
  93         <p>
  94         A networking device is used to actually send and receive the buffers. It either points
  95         to an actual hardware device (in case of ethernet), or to a virtual device (in case of
  96         loopback). Every device has a unique name that identifies it. When creating a device,
  97         the name also decides which net_device module will be chosen; for example, everything
  98         that starts with "loop" will end up in the loopback device, while the ethernet device
  99         accepts names that start with "/dev/net/".
 100         </p>
 101         <p>
 102         A device can be shared by many interfaces at the same time. The device to be used by
 103         an interface is specified at the time an interface is created.
 104         It also has an <code>mtu</code> member that determines the upper limit of an interface's
 105         <code>mtu</code> as well.
 106         </p>
 107         <h4>net_buffer</h4>
 108         <p>
 109         A buffer holds exactly one packet, and has a source as well as a destination address.
 110         The addresses may be changed in every layer the buffer passes through. For example,
 111         the datalink protocols usually use sockaddr_dl structures with family AF_DLI, while
 112         the upper levels may use sockaddr_in structures with family AF_INET. Every protocol
 113         only supports a small number of address types, and it's the requirement of the upper
 114         protocols to prepare the address for use in the lower protocols (and that's also a
 115         reason why it wouldn't work to arbitrarily stack protocols onto each other).
 116         </p>
 117         <p>
 118         The net_buffer module can be used to access the data within the buffer, append new
 119         data to the buffer, or remove chunks of data from it. Internally, the buffer consists
 120         of usually fixed size (2048 byte) buffers that can be shared or connected as needed.
 121         </p>
 122         <h4>net_socket</h4>
 123         <p>
 124         The socket is only of interest for the net_protocol modules, as it stores options
 125         that may have an effect on the protocol's performance. It's the direct counterpart
 126         to a socket file descriptor in userland, but it has only little logic bound to it.
 127         </p>
 128         <p>
 129         When a socket is created, the networking stack creates a chain of net_protocol
 130         modules for the socket that will then do the real work. When the socket is closed,
 131         the net_protocol chain is freed, and the modules are eventually unloaded (if they
 132         are no longer in use).
 133         </p>
 134         <h4>net_protocol</h4>
 135         <p>
 136         The protocols are bound to a specific socket, process the outgoing buffers as needed
 137         (ie. add or remove headers, compute checksums, ...), and pass it on to the next
 138         protocol. The last protocol in the chain is always a domain protocol that will forward
 139         the calls to the datalink module directly, if needed.
 140         </p>
 141         <p>
 142         A domain protocol is a net_protocol that registered a domain, ie. IPv4. Other than usual
 143         protocols, domain protocols have some special requirements:
 144         <ul>
 145         <li>they need to be able to execute send_data(), and get_domain() without a pointer to
 146                 its net_protocol object, as those may be called outside of the socket context.</li>
 147         <li>as mentioned, they also don't talk to the next protocol in the chain (as they are
 148                 always the last one), but to the datalink module directly.</li>
 149         </ul>
 150         </p>
 151         <p>
 152         Similar to the need to perform send_data() outside of the socket context, all protocols
 153         that can receive data need to handle incoming data without the socket context: incoming
 154         data is always handled outside of the socket context, as the actual target socket
 155         is unknown during processing.
 156         </p>
 157         <p>
 158         Only the top-most protocol will be able to forward the packet to the target socket(s).
 159         To receive incoming data, a protocol must register itself as receiving protocol with
 160         the networking stack. The domain protocol is usually registered automatically by a
 161         net_datalink_protocol module that knows about both ends (for example, the ARP
 162         module is both IPv4 and ethernet specific, and therefore registers the AF_INET
 163         domain to receive ethernet packets of type IP).
 164         </p>
 165         <h4>net_datalink_protocol</h4>
 166         <p>
 167         The datalink protocols are bound to a specific net_interface, and therefore to a
 168         specific net_device as well. Outgoing data is processed so that it can be sent
 169         via the net_device. For example, the ARP protocol will replace sockaddr_in structures
 170         in the buffer with sockaddr_dl structures describing the ethernet MAC address of
 171         the source and destination hosts, the ethernet_frame protocol will add the usual
 172         ethernet header, etc.
 173         </p>
 174         <p>
 175         The last protocol in the chain is also a special device interface bridge protocol,
 176         that redirects the calls to the underlying net_device.
 177         </p>
 178         <p>
 179         Incoming data is handled differently again; when you want to receive data directly
 180         coming from a device, you can either register a deframing function for it, or a
 181         handler that will be called depending on what data type the deframing module reported.
 182         For example, the ethernet_frame module registers an ethernet deframing function, while
 183         the ARP module registers a handler for ethernet ARP packets with the device. When the
 184         deframing function reports a <code>ETHER_TYPE_ARP</code> packet, the ARP receiving
 185         function will be called.
 186         </p>
 187         <h4>net_route</h4>
 188         <p>
 189         A route determines the target interface of an outgoing packet. A route is always
 190         owned by a specific domain, and the route is chosen by comparing the networking
 191         address of the outgoing buffer with the mask and address of the route.
 192         </p>
 193         <p>
 194         A protocol will usually not use the routes directly, but use a net_route_info
 195         object (see below), that will make sure that the route is updated automatically
 196         whenever the routing table is changed.
 197         </p>
 198         <h4>net_route_info</h4>
 199         <p>
 200         A routing helper for protocol usage: it stores the target address as well as the
 201         route to be used, and has to be registered with the networking stack via
 202         <code>register_route_info()</code>.
 203         </p>
 204         <p>
 205         Then, the stack will automatically update the route as needed, whenever the
 206         routing table of the domain changes; it will always matches the address specified
 207         there. When the routing is no longer needed, you must unregister the net_route_info
 208         again.
 209         </p>
 210         <hr>
 211         <small>
 212         <a name="foot1">1</a> You can find the definition of the driver interface
 213                 in <a href="http://svn.berlios.de/viewcvs/haiku/haiku/branches/team/network/new_stack/headers_private_net/">headers/private/net/net_stack_driver.h</a>, as well as
 214                 the driver itself at <a href="http://svn.berlios.de/viewcvs/haiku/haiku/branches/team/network/new_stack/add-ons_kernel_drivers_network_stack/">src/add-ons/kernel/drivers/network/stack/</a><br>
 215         <a name="foot2">2</a><a href="http://svn.berlios.de/viewcvs/haiku/haiku/branches/team/network/new_stack/add-ons_kernel_network/stack/">src/add-ons/kernel/network/stack/</a>
 216         </small>
 217 </body>
 218 </html>